home *** CD-ROM | disk | FTP | other *** search
/ Dr. Windows 3 / dr win3.zip / dr win3 / WINPROGS / MINHLP.ZIP / MH.TXT < prev    next >
Text File  |  1993-09-04  |  18KB  |  570 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.                                     MINIHELP
  10.  
  11.  
  12.                     Create Microsoft Windows Help Files in a flash!
  13.  
  14.                     Requirements:
  15.                       Microsoft Windows
  16.                       The HC31.EXE help compiler or its equivalent
  17.                       An ASCII text editor such as QEDIT or NotePad.
  18.  
  19.  
  20.  
  21.                   Copyright 1993 by Tom Campbell.  All Rights Reserved.
  22.  
  23.                   You may use MiniHelp any way you like, as long
  24.                   as you preserve the copyright notices.
  25.  
  26.                   This distribution contains:
  27.  
  28.                     MH.EXE        -- The MiniHelp preprocessor
  29.                     MH.TXT        -- You're reading it!
  30.                     MC.C          -- Source code to MiniHelp
  31.                     TEST?.HPJ     -- Sample help project files.
  32.                     TEST?.SRC     -- Sample MiniHelp source
  33.                                      files.
  34.  
  35.  
  36.  
  37.  
  38. WHAT IT IS
  39.  
  40.   If you've ever tried to create topic source files for the
  41.   Microsoft Windows Help compiler (HC from here on in), you know
  42.   it's a pain.  Commendably enough, Microsoft has made the input
  43.   to HC a subset of RTF or Rich Text Files.  Not all word
  44.   processor support RTF, though.  Even when they do, using RTF
  45.   isn't exactly intuitive.  Finally, you're probably used to
  46.   your own text editor and not all that excited about changing.
  47.  
  48.   MiniHelp works as a go-between, taking its simplified language
  49.   as input and creating as output Help-compliant RTF topic
  50.   files. It offers only a few commands, a mere fraction of the
  51.   rich language that HC understands, but those commands are the
  52.   ones you'll use by far the most often.  You can create the
  53.   first pass using MiniHelp and add things like buttons and
  54.   graphics using RTF later, or just stick with MiniHelp.
  55.   MiniHelp supports easy-to-use versions of these topic file
  56.   features:
  57.  
  58.   - Topic names
  59.   - Titles
  60.   - Keywords
  61.   - Hypertext links
  62.   - Font sizing
  63.   - Comments
  64.  
  65.   That's pretty much it.  I have created complete help systems
  66.   using nothing but MiniHelp because it's fast and easy.
  67.  
  68.   You can of course include standard RTF commands within a
  69.   MiniHelp script, but once you change the output .RTF file, you
  70.   can't read the .RTF file back into MiniHelp to recreate the
  71.   MiniHelp source with the changes you added.  It's a one-way
  72.   process.  (Quit complaining. It's free, after all!)
  73.  
  74. EXAMPLES
  75.  
  76.   Here's a before-and-after example of MiniHelp in action.  This
  77.   is a minimum help topic file in RTF.  It contains a topic
  78.   name, a title, and a few words of text.
  79.  
  80.     {\rtf1\ansi \deff2
  81.     {\fonttbl
  82.     {\f0\froman Times New Roman;}
  83.     {\f1\fdecor Courier New;}
  84.     {\f2\fswiss Arial;}}
  85.     #{\footnote SuperNoteOverview}
  86.     ${\footnote A SuperNote Overview}
  87.     Supernote lets you write several different notes at once.
  88.     \page
  89.     }
  90.  
  91.   Here's the equivalent file written using MiniHelp:
  92.   
  93.     .topic SuperNoteOverview
  94.     .title A SuperNote Overview
  95.      Supernote lets you write several different notes at once.
  96.  
  97.   As you can see, even if you have an RTF-capable editor,
  98.   MiniHelp source files resemble the organization of Windows
  99.   help files much more closely.  And there's a lot less to keep
  100.   track of.  You must remember to end each topic in the RTF file
  101.   with a \page command, you must remember to end the RTF file
  102.   itself with a closing curly brace, you must remember to end
  103.   font names with a semicolon, etc.  MiniHelp lets you forget
  104.   all that and concentrate on getting the job done.
  105.  
  106.   The example above lacked a feature or two, notably keywords
  107.   and hypertext links.  Here's a multitopic help file with table
  108.   of contents, keywords, titles, and hypertext links.
  109.  
  110.     .topic TOFC
  111.     .title Table of Contents
  112.  
  113.     Table of Contents
  114.  
  115.  
  116.     {Find a file anywhere on the disk with FF.EXE:FileFind}
  117.  
  118.     {Finding Today's Files with All2Day:All2day}
  119.  
  120.     .topic FileFind
  121.     .title Find Files on Your Disk
  122.     .keyword FF.EXE;FileFind;files, finding;finding files
  123.     FileFind, or FF.EXE, lets you find files
  124.      anywhere on your disk.  Use it in conjunction with
  125.      {ALL2DAY.EXE:all2day}, which lets you find all
  126.      the files you created today.
  127.  
  128.     See also {Table of Contents:TOFC}
  129.  
  130.     .topic All2Day
  131.     .title Finding the Files You Created Today
  132.     .keyword All2Day;ALL2DAY.EXE;Today
  133.     Whereas {FileFind (FF.EXE):FileFind} searches for the specfied
  134.      file anywhere on your hard disk, All2Day searches the
  135.      default disk for all files created today.
  136.  
  137.     See also {Table of Contents:TOFC}
  138.  
  139.   This may look a bit complex, and it is.  But compare it to the
  140.   RTF version:
  141.  
  142.     {\rtf1\ansi \deff2
  143.     {\fonttbl
  144.     {\f0\froman Times New Roman;}
  145.     {\f1\fdecor Courier New;}
  146.     {\f2\fswiss Arial;}
  147.     }
  148.     #{\footnote TOFC}
  149.     ${\footnote Table of Contents
  150.     }
  151.     \par
  152.     {\uldb Find a file anywhere on the disk with FF.EXE}{\v FILEFIND}
  153.     \par
  154.     {\uldb Finding Today's Files with All2Day}{\v ALL2DAY}
  155.     \par
  156.     \page
  157.     #{\footnote FileFind}
  158.     ${\footnote Find Files on Your Disk}
  159.     K{\footnote  FF.EXE}
  160.     K{\footnote FileFind}
  161.     K{\footnote files, finding}
  162.     K{\footnote finding files}
  163.     FileFind, or FF.EXE, lets you find files
  164.      anywhere on your disk.  Use it in conjunction with
  165.      {\uldb ALL2DAY.EXE}{\v ALL2DAY} , which lets you find all
  166.      the files you created today.
  167.     \par
  168.     See also {\uldb Table of Contents}{\v TOFC}
  169.     \par
  170.     \page
  171.     #{\footnote All2Day}
  172.     ${\footnote Finding the Files You Created Today}
  173.     K{\footnote  All2Day}
  174.     K{\footnote ALL2DAY.EXE}
  175.     Whereas {\uldb FileFind (FF.EXE)}{\v FILEFIND}  searches for the specfied
  176.      file anywhere on your hard disk, All2Day searches the
  177.      default disk for all files created today.
  178.     \par
  179.     See also {\uldb Table of Contents}{\v TOFC}
  180.     \page
  181.     }
  182.  
  183.   As you can see, keeping track of all those nested curly braces
  184.   and backslash commands gets old fast.  MiniHelp can save you
  185.   from all that.
  186.  
  187.  
  188.  
  189. CHAPTER 1. OVERVIEW
  190.  
  191.   MiniHelp creates help topic files.  A topic file contains one
  192.   or more of the following:
  193.  
  194.     1. A topic
  195.     2. A title
  196.     3. Keywords (optional, but strongly recommended)
  197.     4. The topic text itself
  198.  
  199.  You can have multiple topics in a topic file.  The only
  200.  constraint is that topics be given unique names.  Titles are
  201.  not so constrained.
  202.  
  203.  The Microsoft Help Compiler (HC) doesn't use the topic file
  204.  directly, however.  You give it the name of a help project file
  205.  instead.  The help project file has a default extension of .HPJ
  206.  and contains a list of the topic files.
  207.  
  208.  There's a lot going on in a help project file, but you can
  209.  safely ignore all but the [FILES] section.  That's the section
  210.  that names the topic files.  Here's an example of a complete
  211.  help project file named TEST1.HPJ:
  212.  
  213.    [FILES]
  214.    TEST1A.RTF
  215.  
  216.  You have to create the project file yourself; MiniHelp can't do
  217.  it because it doesn't know what files are in the project.  The
  218.  files listed must include full pathnames with extensions.
  219.  Normally, you'll have only one project per directory and keep
  220.  all the topic files in that directory.  In some cases you might
  221.  not want it that way; for example, if you have a standard help
  222.  topic file for the File menu with such unchanging features as
  223.  Save As, Print Setup, and so on, you might wish to keep them in
  224.  a common directory to avoid duplicated effort and maintainence
  225.  problems.
  226.  
  227.  HC "automatically" creates a table of contents; it's whatever
  228.  happens to appear on the first screen of the topic.  See
  229.  TEST2.* for an example.
  230.  
  231.  At any rate, include all of the topic files in your help
  232.  project file.  They may include cross-file references; that is,
  233.  a topic doesn't have to be in file A as long as it appears in
  234.  file B.
  235.  
  236.  The next chapter shows you how to create the topic files using
  237.  MiniHelp.
  238.  
  239.  
  240.  
  241. CHAPTER 2. CREATING A MINIHELP SOURCE FILE
  242.  
  243.   MiniHelp source files contain the text of the help, "dot
  244.   command